<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>Package Documentation for org.apache.struts.taglib.bean Package</title>
</head>
 <body bgcolor="white">
 The "struts-bean" tag library contains JSP custom tags useful in defining
new beans (in any desired scope) from a variety of possible sources, as well
as a tag to render a particular bean (or bean property) to the output response. 
<br>
<br>
 <a name="doc.Description"></a>
 
<div align="Center"> <a href="#doc.Intro">[Introduction]</a>
 <a href="#doc.Properties">[Bean Properties]</a>
 <a href="#doc.Creation">[Bean Creation]</a>
 <a href="#doc.Output">[Bean Output]</a>
 </div>
  
<hr>  <a name="doc.Intro"></a>
 
<h3>Introduction</h3>
  
<p>Much of the power of JavaServer Pages (JSP) technology comes from the
simple and powerful mechanisms by which the servlet that is generated automatically 
from your JSP source page can interact with JavaBeans that represent the computational
state of your application.  In standard JSP pages, the <code>&lt;jsp:useBean&gt;</code>
 tag is used create a bean (if necessary), as well as a "scripting variable"
that can be used within scriptlets to refer to these beans.</p>
  
<p>The "struts-bean" tag library provides substantial enhancements to the 
basic capability provided by <code>&lt;jsp:useBean&gt;</code>, as discussed 
in the following sections:</p>
 
<ul>
 <li><a href="#doc.Properties">Bean Properties</a>
 - Extended syntax to refer to     JavaBean properties with simple names
(same as the standard JSP tags     <code>&lt;jsp:getProperty&gt;</code> and 
    <code>&lt;jsp:setProperty&gt;</code>), nested names (a property named 
    <code>address.city</code> returns the value retrieved by the Java   
 expression <code>getAddress().getCity()</code>), and indexed names     (a
property named <code>address[3]</code> retrieves the fourth address     from
the indexed "address" property of a bean).</li>
 <li><a href="#doc.Creation">Bean Creation</a>
 - New JSP beans, in any scope,     can be created from a variety of objects
and APIs associated with the     current request, or with the servlet container
in which this page is     running.</li>
 <li><a href="#doc.Output">Bean Output</a>
 - Supports the rendering of textual     output from a bean (or bean property),
which will be included in the     response being created by your JSP page.</li>
 
</ul>
  
<p>See the <a href="../../../../../../userGuide/struts-bean.html">Bean Tags Reference</a>
 for detailed information about the available tags in this tag library, and
the valid attributes for each tag.<br>
<img src="doc-files/beanUML.gif" alt="Bean Tag UML">
<br>
</p>
   <a name="doc.Properties"></a>
 
<h3>Bean Properties</h3>
  
<h5>Common Tag Attributes</h5>
  
<p>The tags in the "struts-bean" tag library (and, generally, in all tag libraries
included with the Struts framework) share a common set of tag attributes
that have the same meaning, no matter what tag they are used on. These common
attributes include:</p>
 
<ul>
 <li><em>id</em> - Names the scripting variable that will be     created
by this custom tag, as well as the key value used to locate this     bean
in the scope defined by the <code>scope</code> attribute.</li>
 <li><em>name</em> - Defines the key value by which an existing bean will
be     looked up in the scope defined by the <code>scope</code> attribute 
    (if any), or by searching through the various scopes in the standard 
   order (page, request, session, application).</li>
 <li><em>property</em> - Defines the name of a JavaBeans property, of the
JSP     bean identified by the <code>name</code> and (optional) <code>scope</code>
     attributes, whose value is to be used by this custom tag.  If not  
  specified, the bean identified by <code>name</code> is itself used    
as the value of interest.  See below for more discussion about how a    
property can be referenced.</li>
 <li><em>scope</em> - Identifies the JSP scope ("page", "request", "session", 
    or "application" within which a particular bean will be searched for 
   (under the key specified by the <code>name</code> attribute) or created 
    (under the key specified by the <code>id</code> attribute).  If not 
   specified, beans will generally be searched for in the order listed above, 
    or created in page scope.</li>
 
</ul>
  <a name="doc.Properties.References"></a>
 
<h5>Property References</h5>
  
<p>Struts tags that support the <code>property</code> tag generally also recognize
a rich syntax for getting and setting properties.  There are three types
of references supported:  simple, nested, and indexed.</p>
  
<p><em>Simple References</em> - These are equivalent to the syntax you use
with the standard <code>&lt;jsp:getProperty&gt;</code> and <code>&lt;jsp:setProperty&gt;</code>
 tags.  A reference to a property named "foo" is converted into a method
call to <code>getFoo()</code> or <code>setFoo(value)</code> (as appropriate),
using the standard JavaBeans Specification naming conventions for bean properties.
 Struts uses the standard Java introspection APIs to identify the names of
the actual property getter and setter methods, so your beans can provided
customized method names through the use of a <code>BeanInfo</code> class.
 See the JavaBeans Specification, available at <a href="http://java.sun.com/products/javabeans/">
 http://java.sun.com/products/javabeans/</a>
, for more information.</p>
  
<p><em>Nested References</em> - Nested references are used to access a property
through a hierarchy of property names separated by periods ("."), similar
to the way that nested properties are accessed in JavaScript.  For example,
the following property reference in a getter (such as the <code>&lt;bean:define&gt;</code>
 tag discussed below):</p>
 
<pre>    property="foo.bar.baz"<br></pre>
 
<p>is translated into the equivalent the Java expression:</p>
 
<pre>    getFoo().getBar().getBaz()<br></pre>
 
<p>If a nested reference is used in a setter (such as when an input form
is processed), the property setter is called on the <strong>last</strong>
 property in the chain.  For the above property reference, the equivalent
Java expression would be:</p>
 
<pre>    getFoo().getBar().setBaz(value)<br></pre>
  
<p><em>Indexed References</em> - Subscripts can be used to access individual 
elements of properties whose value is actually an array, or whose underlying 
JavaBean offers indexed getter and setter methods.  For example, the following 
property reference in a getter (such as the <code>&lt;bean:define&gt;</code>
 tag discussed below):</p>
 
<pre>    property="foo[2]"<br></pre>
 
<p>is translated into the equivalent of the Java expression:</p>
 
<pre>    getFoo(2);<br></pre>
 
<p>while the same property reference in a setter would call the equivalent
of:</p>
 
<pre>    setFoo(2, value)<br></pre>
 
<p>As you can see from the above translations, the subscripts used in indexed 
references are <strong>zero relative</strong> (that is, the first element
in an array is <code>foo[0]</code>), just as is true in the Java language.</p>
  
<p><em>Combined References</em> - Nesting and indexing can be combined in 
arbitrary ways, so that expressions like <code>foo.bar[0].baz[2]</code> are 
legal.  You must be careful, of course, to ensure that the actual beans being 
accessed by these references have properties of the appropriate names and 
types.  Otherwise, JSP runtime exceptions will be thrown.</p>
  
<p>See the JavaDocs for <a href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/PropertyUtils.html">PropertyUtils</a>
 for more detailed information about the mechanisms that Struts uses to access 
properties in a general way, through Java reflection APIs.</p>
  
<hr>  <a name="doc.Creation"></a>
 
<h3>Bean Creation</h3>
  
<h5>Introduction</h5>
  
<p>New beans can be created, and introduced into one of the four standard 
JSP scopes (page, request, session, and application) through a variety of 
techniques.  The following subsections describe the use of the following approaches:</p>
 
<ul>
 <li>Java Code in Action Classes</li>
 <li>Java Code in Scriptlets</li>
 <li>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</li>
 <li>The Struts <code>&lt;bean:define&gt;</code> Tag</li>
 <li>Other Struts Copying Tags</li>
 
</ul>
  
<h5>Java Code in Action Classes</h5>
  
<p>Because the JSP pages are compiled into Servlets, your <code>Action</code>
 classes that are invoked by the Struts controller servlet have convenient 
access to three of the four standard JSP scopes (request, session, and application).
 It is very common practice for the business logic contained in your <code>
Action</code> class to create results that are stored in request or session
scope, which will be used by a JSP page you forward control to in rendering
the next page of the user interface.</p>
  
<p><em>Request Scope</em> - To store a bean in request scope under name "cust", 
your <code>Action</code> class would execute code similar to this:</p>
 
<pre>    Customer customer = ... create or acquire a customer reference ...;<br>    request.setAttribute("cust", customer);<br></pre>
  
<p><em>Session Scope</em> - To store a bean in session scope under name "user" 
(perhaps in a logon action), your <code>Action</code> class would execute
code similar to this:</p>
 
<pre>    User user = ... look up valid user in the database ...;<br>    HttpSession session = request.getSession();<br>    session.setAttribute("user", user);<br></pre>
  
<p><em>Application Scope</em> - Generally, application scope beans are initialized
in the <code>init()</code> method of a startup servlet.  However, it is legal
for an <code>Action</code> class to create such beans, if this is appropriate,
like this:</p>
 
<pre>    Foo foo = ... create a Foo ...;<br>    servlet.getServletContext().setAttribute("foo", foo);<br></pre>
  
<h5>Java Code in Scriptlets</h5>
  
<p>While it is not a recommended practice in Struts-based applications (because
developers will be tempted to mix business logic and presentation logic in
their JSP pages), it is legal for scriptlet code in a JSP page to create
new JavaBeans dynamically, and add them to any of the four possible scopes,
as demonstrated in the code examples below:</p>
  
<p><em>Page Scope</em> - To store a bean in page scope under name "foo", your
scriptlet must execute code like this:</p>
 
<pre>&lt;%<br>    Foo foo = ... create a foo ...;<br>    pageContext.setAttribute("foo", foo, PageContext.PAGE_SCOPE);<br>%&gt;<br></pre>
  
<p><em>Request Scope</em> - To store a bean in request scope under name "cust", 
your scriplet must execute code like this:</p>
 
<pre>&lt;%<br>    Customer customer = ... create or acquire a customer reference ...;<br>    pageContext.setAttribute("cust", customer, PageContext.REQUEST_SCOPE);<br>%&gt;<br></pre>
  
<p><em>Session Scope</em> - To store a bean in session scope under name "user", 
(perhaps as a result of a validated login), your scriplet must execute code 
like this:</p>
 
<pre>&lt;%<br>    User user = ... look up valid user in the database ...;<br>    pageContext.setAttribute("user", user, PageContext.SESSION_SCOPE);<br>%&gt;<br></pre>
  
<p><em>Application Scope</em> - Generally, application scope beans are initialized
in the <code>init()</code> method of a startup servlet.  However, a scriptlet
can create such beans, if appropriate, like this:</p>
 
<pre>&lt;%<br>    Foo foo = ... create a Foo ...;<br>    pageContext.setAttribute("foo", foo, PageContext.APPLICATION_SCOPE);<br>%&gt;<br></pre>
  
<p><strong>NOTE</strong> - As mentioned above, using scriptlets in your JSP 
pages is strongly discouraged in a Struts based application, unless you are 
executing code that is <strong>only</strong> related to presentation of existing
data.  In general, your application's processing logic should be encapsulated
in <code>Action</code> classes (or in beans or EJBs called by those classes),
rather than being intermixed in your JSP pages.</p>
  
<h5>The Standard <code>&lt;jsp:useBean&gt;</code> Tag</h5>
  
<p>JavaServer Pages (JSP) offers a standard tag, <code>&lt;jsp:useBean&gt;</code>
 that can be used to create a new bean, or introduce a reference to an existing
bean, into a JSP page.  Beans (or bean references) introduced through this
mechanism are completely interoperable with beans created by any of the Struts
creation techniques described in this section.</p>
  
<p>You <strong>must</strong> use <code>&lt;jsp:useBean&gt;</code> to introduce 
a reference to an existing bean, if you wish to reference that bean with
other standard JSP tags (such as <code>&lt;jsp:getProperty&gt;</code> or <code>
&lt;jsp:setProperty&gt;</code>).  If you only wish to reference such beans
with other Struts tags, use of <code>&lt;jsp:useBean&gt;</code> is not required.</p>
  
<p>For more information about the <code>&lt;jsp:useBean&gt;</code> tag, see 
the JavaServer Pages Specification, available at <a href="http://java.sun.com/products/jsp/download.html">
 http://java.sun.com/products/jsp/download.html</a>
.</p>
  
<h5>The Struts <code>&lt;bean:define&gt;</code> Tag</h5>
  
<p>Struts provides a powerful, general purpose, tag (<code>&lt;bean:define&gt;</code>
) that can be used to create a new bean, in any scope, by copying another
bean (or the value of the property of another bean).  This tag supports the
"property" attribute, and therefore all the power of property references,
as discused <a href="#doc.Properties.References">above</a>
.  It can be used in a variety of different ways, described further below.
 Unless you specify the "toScope" attribute, all defined beans will be created
in page scope.</p>
  
<p><em>Introduce A String Constant</em> - You can create a new bean that
has a constant String value (or the result of calculating a runtime expression): 
</p>
 
<pre>    &lt;bean:define id="foo" value="This is a new String"/&gt;<br>    &lt;bean:define id="bar" value='&lt;%= "Hello, " + user.getName() %&gt;'/&gt;<br>    &lt;bean:define id="last" scope="session"<br>                 value='&lt;%= request.getRequestURI() %&gt;'/&gt;<br></pre>
  
<p><em>Copy An Existing Bean</em> - You can create a new reference to an existing
bean object.  You can specify the Java class or interface the new bean is
expected to conform to with the "type" attribute, or accept the default type
of <code>java.lang.Object</code> (this only affects the scripting variable
that is exposed to scriptlets, so it is not generally meaningful in Struts-based
applications).</p>
 
<pre>    &lt;bean:define id="foo" name="bar"/&gt;<br>    &lt;bean:define id="baz" name="bop" type="com.mycompany.MyBopClass"/&gt;<br></pre>
  
<p><em>Copy An Existing Bean Property</em> - You can create a new bean that 
is initialized to the value returned by a property getter.  The value of
the "property" attribute can be any simple, nested, or indexed property reference 
that follows the rules described earlier.  In the first example below, we 
also illustrate accessing the property of a request scope bean, and creating 
the new bean in session scope (rather than the default page scope).</p>
 
<pre>    &lt;bean:define id="foo" name="bar" property="baz" scope="request"<br>     toScope="session"/&gt;<br>    &lt;bean:define id="bop" name="user" property="role[3].name"/&gt;<br></pre>
  
<h5>Other Struts Copying Tags</h5>
  
<p>Struts offers a variety of bean creation tags that copy existing beans
(or bean properties) from the environment within which this page is running,
and the request that is currently being processed.  Not all of the attributes 
for each tag are illustrated in the examples below - see the <a href="../../../../../../userGuide/struts-bean.html">
Bean Tags Reference</a>
 for more information.  Any bean created by these tags exists only in page 
scope, for the remainder of the current page.</p>
  
<p><em>Copy A Cookie</em> - You can create a new bean containing a <code>
javax.servlet.http.Cookie</code> that was included in the current request.
 If no cookie of the specified name was included, a request time expression
will be thrown - therefore, it is common to nest the use of this tag inside
a <code>&lt;logic:present cookie="xxx"&gt;</code> tag to ensure that the
cookie was really included.  If there is the possibility that more than one
cookie of the same name was included, specify the "multiple" attribute (and
the resulting bean will be an array of Cookies, instead of a single Cookie).</p>
 
<pre>    &lt;bean:cookie id="foo" name="cookiename"/&gt;<br>    &lt;bean:cookie id="all" name="JSESSIONID" multiple="true"/&gt;<br></pre>
  
<p><em>Copy A Request Header</em> - You can create a new bean containing
the value of an HTTP header included in this request.  If no header of the 
specified name was included, a request time exception will be thrown - therefore,
it is common to nest the use of this tag inside a <code>&lt;logic:present
header="xxx"&gt;</code> tag to ensure that the header was really included.
 If there is the possibility that more than one header of the same name was
included, specify the "multiple" attribute (and the resulting value bean
will be an array of String values, instead of a single String).</p>
 
<pre>    &lt;bean:header id="agent" name="User-Agent"/&gt;<br>    &lt;bean:header id="languages" name="Accept-Language" multiple="true"/&gt;<br></pre>
  
<p><em>Copy A Dynamically Created Response</em> - You can generate an internal 
request to the application you are running, and turn the response data that
is returned from that request into a bean (of type String).  One possible
use for this technique is to acquire dynamically created XML formatted data
that will be stored in a bean and later manipulated (such as by applying
an XSLT stylesheet).  If the current request is part of a session, the generated 
request for the include will also include the session identifier (and thus
be considered part of the same session).</p>
 
<pre>    &lt;bean:include id="text" name="/generateXml?param1=a&amp;param2=b"/&gt;<br></pre>
  
<p><em>Copy A JSP Implicitly Defined Object</em> - You can create a bean
that is one of the JSP implicitly defined objects (see the JSP spec for more 
details).  This is useful if you wish to perform property getter actions against
the implicit object with a custom tag instead of a scriptlet.</p>
 
<pre>    &lt;bean:page id="app" property="application"/&gt;<br>    &lt;bean:page id="sess" property="session"/&gt;<br></pre>
  
<p><em>Copy A Request Parameter</em> - You can create a new bean containing
the value of a parameter included in this request.  If no parameter of the 
specified name was included, a request time exception will be thrown - therefore,
it is common to nest the use of this tag inside a <code>&lt;logic:present
parameter="xxx"&gt;</code> tag to ensure that the parameter was really included.
 If there is the possibility that more than one parameter of the same name
was included, specify the "multiple" attribute (and the resulting value bean
will be an array of String values, instead of a single String).</p>
 
<pre>    &lt;bean:parameter id="name" name="name"/&gt;<br>    &lt;bean:header id="options" name="option" multiple="true"/&gt;<br></pre>
  
<p><em>Copy a Web Application Resource</em> - You can create a new bean containing
either the value of a web application resource as a String, or a <code>java.io.InputStream</code>
 for reading the content of that resource. The resource is accessed with
a context-relative path (beginning with "/"), using the <code>ServletContext.getResource()</code>
 or <code>ServletContext.getResourceAsStream()</code> methods on the underlying 
application object.</p>
 
<pre>    &lt;bean:resource id="deployment" name="/WEB-INF/web.xml"/&gt;<br>    &lt;bean:resource id="stream" name="/WEB-INF/web.xml"<br>                   input="true"/&gt;<br></pre>
  
<p><em>Copy A Struts Configuration Object</em> - You can create a new bean 
containing one of the standard Struts framework configuration objects.  Doing 
this gives you access to the properties of the configuration object, if needed. 
</p>
 
<pre>    &lt;bean:struts id="form" formBean="CustomerForm"/&gt;<br>    &lt;bean:struts id="fwd" forward="success"/&gt;<br>    &lt;bean:struts id="map" mapping="/saveCustomer"/&gt;<br></pre>
   
<hr>  <a name="doc.Output"></a>
 
<h3>Bean Output</h3>
  
<p>None of the Struts Bean tags discussed so far render any output to the 
response page that is being generated from this JSP page.  They are executed 
in order to make relevant Java objects visible as beans for further manipulation.
 The following tags cause output to be written to the response, and therefore
made visible to the ultimate requester.</p>
  
<p><em>Render An Internationalized Message</em> - You can specify a message 
key (with optional parameter replacement objects) that are passed to a <a href="../../util/MessageResources.html">
MessageResources</a>
 object that returns the corresponding message text.  The message text will
be copied to the response currently being created.  By default, messages
are looked up in the application resources bundle that is initialized for
you (as an application scope bean) by the Struts controller servlet, using
the Locale must recently stored in the user's session.  These defaults can
be overridden by setting values for the "bundle" and "locale" attributes,
as described in the <a href="../../../../../../userGuide/struts-bean.html#message">
Bean Tags Reference</a>
. </p>
<pre>    &lt;bean:message key="label.Cancel"/&gt;<br>    &lt;bean:message key="message.hello" arg0='&lt;%= user.getFullName() %&gt;'/&gt;<br></pre>
  
<p><em>Render A Bean or Bean Property</em> - The contents of a bean, or bean 
property, are converted to a String and then copied to the response currently 
being created.  This tag understands the syntax for simple, nested, and indexed
property references described <a href="#doc.Properties.Reference"> above</a>
.  Beans from any scope can be requested - by default, the scopes are searched
in expanding visibility order (page, request, session, and application) to
locate the requested bean.</p>
 
<pre>    &lt;bean:write name="username"/&gt;<br>    &lt;bean:write name="user" property="fullName"/&gt;<br>    &lt;bean:write name="customer" property="orders[2].partNumber"<br>                scope="session"/&gt;<br></pre>
  
</body>
</html>
